Generate documentation from zipkin-api Thrift definitions
#98
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Nice find!
…On Mon, Jan 29, 2018 at 12:20 AM, Zoltán Nagy ***@***.***> wrote:
This PR uses the built-in Thrift html generator to generate documentation
from the Thrift source files in zipkin-api. Since there are two source
files, and there may be more in the future, we have two choices. One,
generate separate sites for each source file. Two, generate a dummy wrapper
Thrift source file that references all the modules, and generate a single
documentation site that contains all the modules. The PR currently
implements the latter option, but is easy to adopt for the other one if
that's preferred.
I'm guessing some extra content might be nice, like adding when the
document was generated, and for which version. Maybe even versioning it
along with the API. But I think it's a good first step towards
openzipkin/zipkin-api#21
<openzipkin/zipkin-api#21>.
Expand for screenshot of the doc page for zipkinCore.thrift [image:
screencapture-file-c-users-abesto-appdata-local-lxss-home-abesto-zipkin-api-thrift-gen-html-zipkincore-html-1517156274858]
<https://user-images.githubusercontent.com/59982/35484365-33077a4a-044f-11e8-888d-043331686945.png>
------------------------------
You can view, comment on, or merge this pull request online at:
#98
Commit Summary
- Generate documentation from `zipkin-api` Thrift definitions
File Changes
- *A* generate_docs_from_thrift.sh
<https://github.com/openzipkin/openzipkin.github.io/pull/98/files#diff-0>
(15)
- *A* public/thrift/index.html
<https://github.com/openzipkin/openzipkin.github.io/pull/98/files#diff-1>
(51)
- *A* public/thrift/style.css
<https://github.com/openzipkin/openzipkin.github.io/pull/98/files#diff-2>
(184)
- *A* public/thrift/wrapper.html
<https://github.com/openzipkin/openzipkin.github.io/pull/98/files#diff-3>
(16)
Patch Links:
- https://github.com/openzipkin/openzipkin.github.io/pull/98.patch
- https://github.com/openzipkin/openzipkin.github.io/pull/98.diff
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
<#98>, or mute the
thread
<https://github.com/notifications/unsubscribe-auth/AAD6170RlHQRx_D-Row8_NgHZSy9Hxb6ks5tPJ41gaJpZM4RvwLB>
.
|
|
When linking we should probably be very loud about "v1" eventhough the tags
like http.url are the same. Maybe v1 in the http path or something..
|
|
Tried to pimp out the contents a bit with a quick XSLT transform. Turns out the HTML generated by Thrift is not valid XML. So if we want to modify the content, we'll need some more heavy-handed approach (like, Python or something). Or at least first tidy up the HTML before feeding it through XSLT. Update: |
Also, remove the fake empty "wrapper" module from index.html
|
How about this? Now both the |
|
loud n clear. thanks for doing this! |
|
need to run this again as we added a constant. osx no likey. I changed to greadlink for a quick attempt, but it died later.. $ generate_thrift_v1_docs/generate.sh
++ greadlink -f generate_thrift_v1_docs/generate.sh
+ me=/Users/acole/oss/openzipkin.github.io/generate_thrift_v1_docs/generate.sh
+ '[' 0 -gt 0 ']'
+++ dirname /Users/acole/oss/openzipkin.github.io/generate_thrift_v1_docs/generate.sh
++ cd /Users/acole/oss/openzipkin.github.io/generate_thrift_v1_docs
++ pwd -P
+ mydir=/Users/acole/oss/openzipkin.github.io/generate_thrift_v1_docs
+++ dirname /Users/acole/oss/openzipkin.github.io/generate_thrift_v1_docs
++ cd /Users/acole/oss/openzipkin.github.io
++ pwd -P
+ rootdir=/Users/acole/oss/openzipkin.github.io
+ target_root=/Users/acole/oss/openzipkin.github.io/public
+ target_dir=/Users/acole/oss/openzipkin.github.io/public/thrift/v1
+ rm -rfv /Users/acole/oss/openzipkin.github.io/public/thrift/v1
/Users/acole/oss/openzipkin.github.io/public/thrift/v1/zipkinDependencies.html
/Users/acole/oss/openzipkin.github.io/public/thrift/v1/wrapper.html
/Users/acole/oss/openzipkin.github.io/public/thrift/v1/index.html
/Users/acole/oss/openzipkin.github.io/public/thrift/v1/style.css
/Users/acole/oss/openzipkin.github.io/public/thrift/v1/zipkinCore.html
/Users/acole/oss/openzipkin.github.io/public/thrift/v1
+ mkdir -p /Users/acole/oss/openzipkin.github.io/public/thrift/v1
++ mktemp -d
+ cd /var/folders/9g/60hsfdh12d364162635sjkwr0000gn/T/tmp.vzFaf8uU
+ git clone https://github.com/openzipkin/zipkin-api.git
Cloning into 'zipkin-api'...
remote: Counting objects: 255, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 255 (delta 2), reused 1 (delta 0), pack-reused 249
Receiving objects: 100% (255/255), 1.18 MiB | 451.00 KiB/s, done.
Resolving deltas: 100% (120/120), done.
+ cd zipkin-api/thrift
+ rm -fv wrapper.thrift
+ for source in '*.thrift'
+ echo 'include "zipkinCore.thrift"'
+ for source in '*.thrift'
+ echo 'include "zipkinDependencies.thrift"'
+ thrift -r --gen html -I . -out /Users/acole/oss/openzipkin.github.io/public/thrift/v1 wrapper.thrift
+ set +e
+ tidy -indent -asxml -output /Users/acole/oss/openzipkin.github.io/public/thrift/v1/index.tidy.html /Users/acole/oss/openzipkin.github.io/public/thrift/v1/index.html
line 1 column 1 - Warning: missing <!DOCTYPE> declaration
line 6 column 74 - Warning: missing <tr>
line 10 column 7 - Warning: discarding unexpected </code>
line 44 column 1 - Warning: discarding unexpected </code>
line 50 column 7 - Warning: discarding unexpected </code>
line 6 column 1 - Warning: <table> lacks "summary" attribute
Info: Document content looks like XHTML 1.0 Strict
6 warnings, 0 errors were found!
The table summary attribute should be used to describe
the table structure. It is very helpful for people using
non-visual browsers. The scope and headers attributes for
table cells are useful for specifying which headers apply
to each table cell, enabling non-visual browsers to provide
a meaningful context for each cell.
For further advice on how to make your pages accessible
see http://www.w3.org/WAI/GL. You may also want to try
"http://www.cast.org/bobby/" which is a free Web-based
service for checking URLs for accessibility.
To learn more about HTML Tidy see http://tidy.sourceforge.net
Please send bug reports to html-tidy@w3.org
HTML and CSS specifications are available from http://www.w3.org/
Lobby your company to join W3C, see http://www.w3.org/Consortium
+ tidy_status=1
+ '[' 1 -gt 1 ']'
+ set -e
+ java -jar /usr/share/java/Saxon-HE.jar -s:/Users/acole/oss/openzipkin.github.io/public/thrift/v1/index.tidy.html -xsl:/Users/acole/oss/openzipkin.github.io/generate_thrift_v1_docs/transform.xslt -o:/Users/acole/oss/openzipkin.github.io/public/thrift/v1/index.baked.html
Error: Unable to access jarfile /usr/share/java/Saxon-HE.jar |
|
Right. I didn't do a great job documenting the requirements, esp. not on checking them. I guess a Docker container that can run this would be ideal at some point, but for now I'm just gonna re-run this from the same env. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR uses the built-in Thrift
htmlgenerator to generate documentation from the Thrift source files inzipkin-api. Since there are two source files, and there may be more in the future, we have two choices. One, generate separate sites for each source file. Two, generate a dummy wrapper Thrift source file that references all the modules, and generate a single documentation site that contains all the modules. The PR currently implements the latter option, but is easy to adopt for the other one if that's preferred.I'm guessing some extra content might be nice, like adding when the document was generated, and for which version. Maybe even versioning it along with the API. But I think it's a good first step towards openzipkin/zipkin-api#21.
Expand for screenshot of the doc page for
zipkinCore.thrift